home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / SetVar.3 < prev    next >
Text File  |  1994-09-20  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_SetVar(3)        Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_SetVar,    Tcl_SetVar2,     Tcl_GetVar,     Tcl_GetVar2,
  12.      Tcl_UnsetVar, Tcl_UnsetVar2 - manipulate Tcl variables
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      char *
  18.      Tcl_SetVar(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  19.  
  20.      char *
  21.      Tcl_SetVar2(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  22.  
  23.      char *
  24.      Tcl_GetVar(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  25.  
  26.      char *
  27.      Tcl_GetVar2(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  28.  
  29.      int
  30.      Tcl_UnsetVar(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  31.  
  32.      int
  33.      Tcl_UnsetVar2(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  34.  
  35. ARGUMENTS
  36.      Tcl_Interp   *_i_n_t_e_r_p     (in)      Interpreter    containing
  37.                                         variable.
  38.  
  39.      char         *_v_a_r_N_a_m_e    (in)      Name  of  variable.   May
  40.                                         refer  to  a scalar vari-
  41.                                         able or an element of  an
  42.                                         array variable.
  43.  
  44.      char         *_n_e_w_V_a_l_u_e   (in)      New value for variable.
  45.  
  46.      int          _f_l_a_g_s       (in)      OR-ed combination of bits
  47.                                         providing      additional
  48.                                         information  for   opera-
  49.                                         tion. See below for valid
  50.                                         values.
  51.  
  52.      char         *_n_a_m_e_1      (in)      Name of scalar  variable,
  53.                                         or name of array variable
  54.                                         if _n_a_m_e_2 is non-NULL.
  55.  
  56.      char         *_n_a_m_e_2      (in)      If non-NULL,  gives  name
  57.                                         of  element  within array
  58.                                         and _n_a_m_e_1 must  refer  to
  59.                                         an array variable.
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SetVar(3)        Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74. _________________________________________________________________
  75.  
  76.  
  77. DESCRIPTION
  78.      These procedures may be used to create,  modify,  read,  and
  79.      delete   Tcl   variables   from   C  code.   Tcl_SetVar  and
  80.      Tcl_SetVar2 will create a new variable or modify an existing
  81.      one.  Both of these procedures set the given variable to the
  82.      value given by _n_e_w_V_a_l_u_e, and they return a pointer to a copy
  83.      of  the variable's new value, which is stored in Tcl's vari-
  84.      able structure.  Tcl keeps a private copy of the  variable's
  85.      value,  so  the  caller may change _n_e_w_V_a_l_u_e after these pro-
  86.      cedures return without affecting the value of the  variable.
  87.      If  an  error  occurs in setting the variable (e.g. an array
  88.      variable is referenced without  giving  an  index  into  the
  89.      array), then NULL is returned.
  90.  
  91.      The name of the variable may be specified in either  of  two
  92.      ways.   If  Tcl_SetVar is called, the variable name is given
  93.      as a single string, _v_a_r_N_a_m_e.  If _v_a_r_N_a_m_e  contains  an  open
  94.      parenthesis  and  ends  with  a  close parenthesis, then the
  95.      value between the parentheses is treated as an index  (which
  96.      can  have  any  string  value) and the characters before the
  97.      first open parenthesis are treated as the name of  an  array
  98.      variable.   If _v_a_r_N_a_m_e doesn't have parentheses as described
  99.      above, then the entire string is treated as the  name  of  a
  100.      scalar  variable.   If Tcl_SetVar2 is called, then the array
  101.      name and index have been separated by the  caller  into  two
  102.      separate strings, _n_a_m_e_1 and _n_a_m_e_2 respectively;  if _n_a_m_e_2 is
  103.      zero it means that a scalar variable is being referenced.
  104.  
  105.      The _f_l_a_g_s argument may be used to  specify  any  of  several
  106.      options to the procedures.  It consists of an OR-ed combina-
  107.      tion of any of the following bits:
  108.  
  109.      TCL_GLOBAL_ONLY
  110.           Under normal circumstances the procedures look up vari-
  111.           ables  at  the  current  level  of  procedure  call for
  112.           _i_n_t_e_r_p, or at global level if there is no call  active.
  113.           However,  if this bit is set in _f_l_a_g_s then the variable
  114.           is looked up at global level even if there  is  a  pro-
  115.           cedure call active.
  116.  
  117.      TCL_LEAVE_ERR_MSG
  118.           If an error is returned and this bit is set  in  _f_l_a_g_s,
  119.           then  an  error message will be left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  120.           If this flag bit isn't set then  no  error  message  is
  121.           left (_i_n_t_e_r_p->_r_e_s_u_l_t will not be modified).
  122.  
  123.      TCL_APPEND_VALUE
  124.           If this bit is set then _n_e_w_V_a_l_u_e  is  appended  to  the
  125.           current   value,  instead  of  replacing  it.   If  the
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SetVar(3)        Tcl Library Procedures                   7.0
  137.  
  138.  
  139.  
  140.           variable is  currently  undefined,  then  this  bit  is
  141.           ignored.
  142.  
  143.      TCL_LIST_ELEMENT
  144.           If this bit is set, then _n_e_w_V_a_l_u_e  is  converted  to  a
  145.           valid Tcl list element before setting (or appending to)
  146.           the variable.  A separator space is appended before the
  147.           new list element unless the list element is going to be  |
  148.           the first element  in  a  list  or  sublist  (i.e.  the  |
  149.           variable's current value is empty, or contains the sin-  |
  150.           gle character ``{'', or ends in `` }'').
  151.  
  152.      Tcl_GetVar and Tcl_GetVar2 return the  current  value  of  a
  153.      variable.   The arguments to these procedures are treated in
  154.      the same way as the arguments to Tcl_SetVar and Tcl_SetVar2.
  155.      Under normal circumstances, the return value is a pointer to
  156.      the variable's value (which  is  stored  in  Tcl's  variable
  157.      structure  and  will  not  change  before  the  next call to
  158.      Tcl_SetVar or Tcl_SetVar2).  The only bits of _f_l_a_g_s that are
  159.      used  are  TCL_GLOBAL_ONLY  and  TCL_LEAVE_ERR_MSG,  both of
  160.      which have the same meaning as for Tcl_SetVar.  If an  error
  161.      occurs  in  reading  the variable (e.g. the variable doesn't
  162.      exist or an array element is specified for  a  scalar  vari-
  163.      able), then NULL is returned.
  164.  
  165.      Tcl_UnsetVar and Tcl_UnsetVar2 may be used to remove a vari-
  166.      able,  so that future calls to Tcl_GetVar or Tcl_GetVar2 for
  167.      the variable will return an error.  The arguments  to  these
  168.      procedures  are  treated in the same way as the arguments to
  169.      Tcl_GetVar and Tcl_GetVar2.  If the variable is successfully  |
  170.      removed  then TCL_OK is returned.  If the variable cannot be  |
  171.      removed because it doesn't exist then TCL_ERROR is returned.
  172.      If  an  array  element  is  specified,  the given element is
  173.      removed but the array remains.  If an array name  is  speci-
  174.      fied without an index, then the entire array is removed.
  175.  
  176.  
  177. SEE ALSO
  178.      Tcl_TraceVar
  179.  
  180.  
  181. KEYWORDS
  182.      array, interpreter, scalar, set, unset, variable
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.